<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  <html xmlns="http://www.w3.org/1999/xhtml">
		<head>
			<!-- template designed by Marco Von Ballmoos -->
			<title>Log User Guide</title>
			<link rel="stylesheet" href="../../media/stylesheet.css" />
			<meta http-equiv='Content-Type' content='text/html; charset=iso-8859-1'/>
		</head>
		<body>
			<div class="page-body">			
	<table class="tutorial-nav-box">
	<tr>
		<td style="width: 30%">
							<a href="../../event/tutorial_event.pkg.html" class="nav-button">Previous</a>
					</td>
		<td style="text-align: center">
					</td>
		<td style="text-align: right; width: 30%">
							<span class="nav-button-disabled">Next</span>
					</td>
	</tr>
	<tr>
		<td style="width: 30%">
							<span class="detail">Event and Log Documentation</span>
					</td>
		<td style="text-align: center">
					</td>
		<td style="text-align: right; width: 30%">
					</td>
	</tr>
</table>
	
<div><a name=""></a><div class="ref-title-box"><h1 class="ref-title">Log User Guide</h1>
		<h2 class="ref-purpose"></h2></div>
	<div class="ref-synopsis"><span class="author">Gerrit Jan van Ahee
			<div class="author-blurb"><a href="mailto:gerrit.jan@yes2web.nl">Gerrit Jan van Ahee</a></div></span></div>
	<span><a name="intro"></a><p>A logger is implemented as an event handler, which makes sense as one would like to log certain events.
		For this purpose, the default event handler (Event_Handler) has been extended by a Event_Logger.
		These have a member variable that extends Log_Store, containing a store, such as a file or a db
		connection, to store messages in.</p>
		<p><div class="title">Logging Messages</div>Event_Loggers provide the log() method that take an Event_Log_Message instance. These wrap generic
		functionality into one class, requiring only a FORMAT constant: a <a href="http://www.php.net/sprintf">sprintf</a>
		format.</p>
		<div class="src-code"><ol><li><div class="src-line"><span class="src-key">class&nbsp;</span><span class="src-id">A_Log_Message&nbsp;</span><span class="src-key">extends&nbsp;</span><span class="src-id">Log_Message&nbsp;</span><span class="src-sym">{</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">const&nbsp;</span><span class="src-id">FORMAT&nbsp;</span>=&nbsp;<span class="src-str">'&nbsp;Message:&nbsp;%2$s&nbsp;[%s]'</span><span class="src-sym">;</span></div></li>
<li><div class="src-line"><span class="src-sym">}</span></div></li>
</ol></div>
		<p>The placeholders will map to the arguments provided to the constructor:</p>
		<div class="src-code"><ol><li><div class="src-line">(string)&nbsp;<span class="src-key">new&nbsp;</span><span class="src-id">A_Log_Message</span><span class="src-sym">(</span><span class="src-str">'one'</span><span class="src-sym">,&nbsp;</span><span class="src-str">'two'</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li>
</ol></div>
		<p>will result in the string like &quot;2010-12-10 14:07:12 - 82.132.442.04 Message: two [one]&quot;</p>
		<p>If you need a different method, extend it and provide your own constant FORMAT. The number of placeholders
		should match the number of arguments, though there's no need to redeclare the constructor. If you don't
		need the prefix &quot;2010-12-10 14:07:12 - 82.132.442.04&quot;, override the <a href="../../event/log/Event_Log_Message.html#methodprefix">prefix()</a>
		method to return something else.</p>
		<div class="src-code"><ol><li><div class="src-line"><span class="src-key">class&nbsp;</span><span class="src-id">Another_Log_Message&nbsp;</span><span class="src-key">extends&nbsp;</span><a href="../../event/log/Event_Log_Message.html">Event_Log_Message</a>&nbsp;<span class="src-sym">{</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">const&nbsp;</span><span class="src-id">FORMAT&nbsp;</span>=&nbsp;<span class="src-str">'This&nbsp;%2$s&nbsp;%s&nbsp;%s'</span><span class="src-sym">;</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">protected&nbsp;</span><span class="src-key">function&nbsp;</span><span class="src-id">prefix</span><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">{&nbsp;</span><span class="src-key">return&nbsp;</span><span class="src-str">''</span><span class="src-sym">;&nbsp;</span><span class="src-sym">}</span></div></li>
<li><div class="src-line"><span class="src-sym">}</span></div></li>
<li><div class="src-line">(string)&nbsp;<span class="src-key">new&nbsp;</span><span class="src-id">Another_Log_Message</span><span class="src-sym">(</span><span class="src-str">'something'</span><span class="src-sym">,&nbsp;</span><span class="src-str">'returns'</span><span class="src-sym">,&nbsp;</span><span class="src-str">'else'</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li>
</ol></div>
		<p>will return the string &quot;This returns something else&quot;.</p>
		
		<p><div class="title">Setting up Logging</div>Being event handlers, Loggers listen to interesting events from multiple classes/interfaces, providing a uniform
		message log for all these types.</p>
		<p>Additionally, loggers can also use the onException event handler, allowing easy logging of Exceptions
		originating in the types listened to.</p>
		<p>Example of a logger</p>
		<div class="src-code"><ol><li><div class="src-line"><span class="src-key">class&nbsp;</span><span class="src-id">A_Logger&nbsp;</span><span class="src-key">extends&nbsp;</span><span class="src-id">Event_Logger&nbsp;</span><span class="src-sym">{&nbsp;</span><span class="src-comm">#&nbsp;specifically&nbsp;for&nbsp;A_Class-es</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">public&nbsp;</span><span class="src-key">function&nbsp;</span><span class="src-id">onBeforeCreate</span><span class="src-sym">(</span><span class="src-id">Event_Event&nbsp;</span><span class="src-var">$oEvent</span><span class="src-sym">)</span><span class="src-sym">{</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-var">$this</span><span class="src-sym">-&gt;</span><span class="src-id">log</span><span class="src-sym">(</span><span class="src-key">new&nbsp;</span><span class="src-id">A_Log_Message</span><span class="src-sym">(</span><span class="src-var">$oEvent</span><span class="src-sym">-&gt;</span><span class="src-id">getType</span><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">,&nbsp;</span><span class="src-str">'NEW&nbsp;A_CLASS'</span><span class="src-sym">))</span><span class="src-sym">;</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-var">$this</span><span class="src-sym">-&gt;</span><span class="src-id">log</span><span class="src-sym">(</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">new&nbsp;</span><span class="src-id">A_Log_Message</span><span class="src-sym">(</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-var">$oEvent</span><span class="src-sym">-&gt;</span><span class="src-id">getType</span><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">,</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://www.php.net/implode">implode</a><span class="src-sym">(</span><span class="src-str">',&nbsp;'</span><span class="src-sym">,&nbsp;</span><span class="src-var">$oEvent</span><span class="src-sym">-&gt;</span><span class="src-id">getArgs</span><span class="src-sym">(</span><span class="src-sym">)</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-sym">)</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-sym">)</span><span class="src-sym">;</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-sym">}</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">public&nbsp;</span><span class="src-key">function&nbsp;</span><span class="src-id">onAfterCreate</span><span class="src-sym">(</span><span class="src-id">Event_Event&nbsp;</span><span class="src-var">$oEvent</span><span class="src-sym">)</span><span class="src-sym">{</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-var">$this</span><span class="src-sym">-&gt;</span><span class="src-id">log</span><span class="src-sym">(</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">new&nbsp;</span><span class="src-id">A_Log_Message</span><span class="src-sym">(</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-var">$oEvent</span><span class="src-sym">-&gt;</span><span class="src-id">getType</span><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">,</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://www.php.net/implode">implode</a><span class="src-sym">(</span><span class="src-str">',&nbsp;'</span><span class="src-sym">,&nbsp;</span><span class="src-var">$oEvent</span><span class="src-sym">-&gt;</span><span class="src-id">getArgs</span><span class="src-sym">(</span><span class="src-sym">))</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-sym">)</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-sym">)</span><span class="src-sym">;</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-var">$this</span><span class="src-sym">-&gt;</span><span class="src-id">log</span><span class="src-sym">(</span><span class="src-key">new&nbsp;</span><span class="src-id">A_Log_Message</span><span class="src-sym">(</span><span class="src-var">$oEvent</span><span class="src-sym">-&gt;</span><span class="src-id">getType</span><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">,&nbsp;</span><span class="src-str">'A_CLASS&nbsp;CREATED'</span><span class="src-sym">))</span><span class="src-sym">;</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-sym">}</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">public&nbsp;</span><span class="src-key">function&nbsp;</span><span class="src-id">onException</span><span class="src-sym">(</span><span class="src-id">Event_Exception&nbsp;</span><span class="src-var">$oEvent</span><span class="src-sym">)</span><span class="src-sym">{</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-var">$oEx&nbsp;</span>=&nbsp;<span class="src-var">$oEvent</span><span class="src-sym">-&gt;</span><span class="src-id">getException</span><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-var">$this</span><span class="src-sym">-&gt;</span><span class="src-id">log</span><span class="src-sym">(</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">new&nbsp;</span><span class="src-id">A_Log_Message</span><span class="src-sym">(</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-str">'Exception'</span><span class="src-sym">,</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-var">$oEx</span><span class="src-sym">-&gt;</span><span class="src-id">getMessage</span><span class="src-sym">(</span><span class="src-sym">)</span>.<span class="src-str">'#'</span>.<span class="src-var">$oEx</span><span class="src-sym">-&gt;</span><span class="src-id">getCode</span><span class="src-sym">(</span><span class="src-sym">)</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-sym">)</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-sym">)</span><span class="src-sym">;</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-sym">}</span></div></li>
<li><div class="src-line"><span class="src-sym">}</span></div></li>
</ol></div>
		<p>Attaching the example to A_Class and B_Class objects and have it log its messages to a file in this folder</p>
		<div class="src-code"><ol><li><div class="src-line"><span class="src-key">new&nbsp;</span><span class="src-id">A_Logger</span><span class="src-sym">(</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-key">new&nbsp;</span><span class="src-id">Your_Log_Device_Impl</span><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">,</span></div></li>
<li><div class="src-line">&nbsp;&nbsp;&nbsp;&nbsp;<span class="src-str">'A_Class'</span><span class="src-sym">,&nbsp;</span><span class="src-str">'B_Class'</span></div></li>
<li><div class="src-line"><span class="src-sym">)</span><span class="src-sym">;</span></div></li>
</ol></div></span></div>

	<table class="tutorial-nav-box">
	<tr>
		<td style="width: 30%">
							<a href="../../event/tutorial_event.pkg.html" class="nav-button">Previous</a>
					</td>
		<td style="text-align: center">
					</td>
		<td style="text-align: right; width: 30%">
							<span class="nav-button-disabled">Next</span>
					</td>
	</tr>
	<tr>
		<td style="width: 30%">
							<span class="detail">Event and Log Documentation</span>
					</td>
		<td style="text-align: center">
					</td>
		<td style="text-align: right; width: 30%">
					</td>
	</tr>
</table>
	
	<p class="notes" id="credit">
		Documentation generated on Thu, 19 May 2011 10:21:00 +0200 by <a href="http://www.phpdoc.org" target="_blank">phpDocumentor 1.4.3</a>
	</p>
	</div></body>
</html>